{
  "info": {
    "_postman_id": "49f8b938-39fd-4d71-a15a-3da0d040c2fd",
    "name": "Rackrr API",
    "description": "Complete API documentation for Rackrr\n\n**Required Environment:** Rackrr Environment\n\nTo link the environment:\n\n1. Import both the collection and environment files\n    \n2. In Postman, go to the collection settings (three dots → Edit)\n    \n3. Go to the 'Variables' tab\n    \n4. Or simply select 'Rackrr Environment' from the environment dropdown in the top right\n    \n\n**Environment Variables:**\n\n- baseUrl: API base URL (default: [https://api.rackrr.ai/v1](https://api.rackrr.ai/v1))\n    \n- authToken: Your Rackrr API key — generate one from the API Keys page in the dashboard",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_exporter_id": "33028597"
  },
  "item": [
    {
      "name": "Virtual Machines",
      "item": [
        {
          "name": "Get Available VMs",
          "request": {
            "method": "GET",
            "description": "Retrieve a list of all GPU virtual machines currently available for provisioning. Returns hardware specs, GPU models, pricing, and availability status for each VM option.\n\n**Auth:** API key required\n\n**Response:** Array of available VM configurations with GPU model, vCPU, RAM, storage, and hourly pricing.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/vms/available",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "vms",
                "available"
              ]
            }
          },
          "response": []
        },
        {
          "name": "Get VMs",
          "request": {
            "method": "GET",
            "description": "Retrieve a list of all virtual machines belonging to the authenticated user. Returns the status, configuration, provider info, and usage metrics for each VM.\n\n**Auth:** API key required\n\n**Response:** Array of VM objects with status, GPU model, resource allocation, and connection details.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/vms",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "vms"
              ]
            }
          },
          "response": []
        },
        {
          "name": "Get VM by ID",
          "request": {
            "method": "GET",
            "description": "Fetch full details of a single virtual machine by its ID. Includes real-time status, hardware specs, provider info, SSH/connection credentials, and cost breakdown.\n\n**Auth:** API key required\n\n**Path Parameters:**\n- `id` (string, required): The VM's database ID (e.g. `69b6bc8d1d251b6d65ec47d4`)\n\n**Response:** Full VM document with status, GPU config, networking, and billing info.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/vms/:id",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "vms",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "69b6bc8d1d251b6d65ec47d4"
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "Provision VM",
          "request": {
            "method": "POST",
            "description": "Provision (create and start) a new GPU virtual machine on the specified provider. This initiates the full VM lifecycle — hardware allocation, OS boot, and network setup.\n\n**Auth:** API key required\n\n**Request Body:**\n- `provider_id` (string, required): UUID of the cloud provider\n- `provider_ref` (string, required): Database ID of the provider record\n- `gpu_model` (string, required): GPU model slug (e.g. `geforcertx4090-pcie-24gb`)\n- `gpu_count` (integer, required): Number of GPUs to allocate\n- `vcpus` (integer, required): Number of virtual CPUs (must be even)\n- `ram` (integer, required): RAM in GB (must be even)\n- `storage` (integer, required): Storage in GB\n- `user_provided_name` (string, required): A friendly name for the VM\n- `ssh_public_key` (string, required): Your SSH public key (e.g. `ssh-ed25519 AAAA...`). The platform will configure the VM to accept connections using your key. Connect with your own private key — no private key is returned in the response.\n\n**Response:** Newly created VM object with ID, status, and connection details.",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"provider_id\": \"79a92e6d-e93b-4af3-9f51-bb04ea2e52ff\",\n  \"provider_ref\": \"69079afc14990d2b138271cd\",\n  \"gpu_model\": \"geforcertx4090-pcie-24gb\",\n  \"gpu_count\": 1,\n  \"vcpus\": 4,\n  \"ram\": 8,\n  \"storage\": 100,\n  \"user_provided_name\": \"my-vm\",\n  \"ssh_public_key\": \"ssh-ed25519 AAAA...your-public-key... user@host\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/vms/provision",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "vms",
                "provision"
              ]
            }
          },
          "response": []
        },
        {
          "name": "Start VM",
          "request": {
            "method": "POST",
            "description": "Start a previously stopped virtual machine. The VM must be in a `stopped` state before calling this endpoint.\n\n**Auth:** API key required\n\n**Path Parameters:**\n- `id` (string, required): The VM's database ID\n\n**Response:** Updated VM object with new status (`starting` → `running`).",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/vms/:id/start",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "vms",
                ":id",
                "start"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "Stop VM",
          "request": {
            "method": "POST",
            "description": "Gracefully stop a running virtual machine. The VM will be shut down but its disk and configuration are preserved. Billing may pause depending on the provider.\n\n**Auth:** API key required\n\n**Path Parameters:**\n- `id` (string, required): The VM's database ID\n\n**Response:** Updated VM object with new status (`stopping` → `stopped`).",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/vms/:id/stop",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "vms",
                ":id",
                "stop"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "Terminate VM",
          "request": {
            "method": "POST",
            "description": "Permanently terminate and destroy a virtual machine. This is irreversible — all data on the VM will be deleted and the hardware released back to the provider pool.\n\n**Auth:** API key required\n\n**Path Parameters:**\n- `id` (string, required): The VM's database ID\n\n**Warning:** This action cannot be undone. All unsaved data will be lost.\n\n**Response:** Confirmation of termination with final VM status.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/vms/:id/terminate",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "vms",
                ":id",
                "terminate"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "69b86dc4034b9d7fc8ba956c"
                }
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Wallet",
      "item": [
        {
          "name": "Get Wallet Balance",
          "request": {
            "method": "GET",
            "description": "Retrieve the current wallet balance for the authenticated user. Returns the available credit balance used to pay for GPU compute time.\n\n**Auth:** API key required\n\n**Response:** Wallet object with current balance, currency, and last updated timestamp.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/wallets/balance",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "wallets",
                "balance"
              ]
            }
          },
          "response": []
        },
        {
          "name": "Get Transactions",
          "request": {
            "method": "GET",
            "description": "Retrieve the transaction history for the authenticated user's wallet. Includes charges for VM usage, top-ups, and refunds.\n\n**Auth:** API key required\n\n**Response:** Array of transaction records with amount, type (`debit`/`credit`), description, and timestamp.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/wallets/transactions",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "wallets",
                "transactions"
              ]
            }
          },
          "response": []
        }
      ]
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{authToken}}",
        "type": "string"
      }
    ]
  },
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Validate environment variables",
          "const baseUrl = pm.environment.get('baseUrl') || pm.collectionVariables.get('baseUrl');",
          "",
          "if (!baseUrl) {",
          "    console.warn('⚠️  Warning: baseUrl is not set. Please select the Rackrr Environment or set baseUrl in collection variables.');",
          "    console.log('💡 Tip: Set baseUrl to https://api.rackrr.ai/v1 in the environment dropdown.');",
          "} else {",
          "    console.log('✅ baseUrl:', baseUrl);",
          "}",
          "",
          "const authToken = pm.environment.get('authToken') || pm.collectionVariables.get('authToken');",
          "if (!authToken) {",
          "    console.warn('⚠️  Warning: authToken is not set. Generate an API key from the Rackrr dashboard and set it in the authToken environment variable.');",
          "}"
        ]
      }
    },
    {
      "listen": "test",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Set your Rackrr API key in the authToken environment variable."
        ]
      }
    }
  ],
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.rackrr.ai/v1"
    },
    {
      "key": "authToken",
      "value": ""
    }
  ]
}